/* vim: set expandtab tabstop=4 softtabstop=4 shiftwidth=4: */
/* Copyright (C) 2012 Zongyou Yao. All rights reserved.     */

#ifndef STACK_INCLUDED
#define STACK_INCLUDED

/**
 * It is a checked runtime error to pass null stack_t to any stack function.
 */
typedef struct stack_t *stack_t;

/**
 * Returns a new, empty stack_t.
 * Exception mem_failed can be raised.
 */
stack_t stack_new(void);

/**
 * Returns one if stk is empty and zero otherwise.
 */
int stack_empty(stack_t stack);

/**
 * Pushes x onto stk.
 * Exception mem_failed can be raised.
 */
void stack_push(stack_t stack, void *x);

/**
 * Pops and returns the top element on stk. It is a checked runtime error for stk
 * to be empty.
 */
void * stack_pop(stack_t stack);

/**
 * Deallocates and clears *stk. It is a checked runtime error for stk or *stk 
 * to be null.
 */
void stack_free(stack_t *stack);

#endif
